home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / indx18eu.zip / READ.ME < prev    next >
Text File  |  1991-03-20  |  18KB  |  422 lines
  1. 03 / 20 / 1991
  2.  
  3. FILE :  READ.ME
  4.  
  5. ***************************************************************************
  6.  
  7. DISCLAIMER :
  8.  
  9.       This file and its related contents are to be used at the risk of
  10.       those using it.  None of these routines are guaranteed to work and any
  11.       damage resulting from the use of anything included is the sole
  12.       responsibility of those USING IT.
  13.  
  14.       This file and all source provided are considered copyrighted.
  15.  
  16.       You are encouraged to use this material provided it is for non-
  17.       commercial use.  Those wishing ( for some reason :-) ) to use this
  18.       for a commercial product, please contact the author.
  19.  
  20.       You are encouraged to give this package away AS A PACKAGE.  The source
  21.       is not to be modify before exchange; however, feel free to modify for
  22.       personal use only.  Contact the author with any changes please as I
  23.       like to see good improvements!
  24.  
  25.       Finally, if you wish to send anything ( other source code included )
  26.       for good faith, joy & money accepted ;-), Please send to :
  27.  
  28.         Thomas Jenkins                       ( USA )
  29.         9732 Windsor Lake Blvd.
  30.         Columbia, SC 29223
  31.  
  32.         E-Mail :  BITNET   :   C0361 @ UNIVSCVM
  33.                   INTERNET :   C0361 @ UNIVSCVM.CSD.SCAROLINA.EDU
  34.  
  35.         Comments :  ( 803 ) 777-6666 wk              ( USA )
  36.                     ( 803 ) 788-7179 hm
  37.  
  38. ***************************************************************************
  39.  
  40.                   SECTION ONE:  IndexedFiles
  41.  
  42. ***************************************************************************
  43. **  From version 1.7 to version 1.8 there have been Major changes to     **
  44. **  IndexedFiles.  I've had to delete the encryption section to make     **
  45. **  file available on as many sites as possible.  I apologize for any   **
  46. **  inconvenience this may cause.  If anyone wishes to ask me about my  **
  47. **  Encryption schemes, please feel free to contact me since this is not **
  48. **  considered illegal ( just actually providing code *sigh* ).          **
  49. **                                                           **
  50. ***************************************************************************
  51.  
  52. The following is the variable exported by IndexedFiles:
  53.  
  54.        fileError                                 : WORD ;
  55.  
  56. The following is a list of all error codes returned in fileError:
  57.  
  58.        NO_ERROR                                  = 0
  59.        NOT_ENOUGH_MEMORY                         = 1
  60.        READ_LESS_BYTES_THAN_EXPECTED             = 2
  61.        INDEX_NOT_FOUND                           = 3
  62.        LESS_BYTES_WRITTEN_THAN_EXPECTED          = 4
  63.        INVALID_FILE_NAME                         = 5
  64.  
  65.  
  66.   Of course the standard error variables in Turbo will report errors as well:
  67.     EX, DOSError.
  68.  
  69.  
  70. The following is a list of types exported by IndexedFiles:
  71.  
  72.  
  73.        IndexStr                                  = STRING [ 010 ] ;
  74.  
  75.        IFile                                     = RECORD
  76.  
  77.          baseFile                                : FILE ;
  78.          indexFile                               : FILE ;
  79.  
  80.          fileName                                : STRING ;
  81.  
  82.        END ;  {  IFile  }
  83.  
  84.        IndexType                                 = RECORD
  85.  
  86.          index                                   : IndexStr ;
  87.          position                                : LONGINT ;
  88.  
  89.        END ;  {  IndexType  }
  90.  
  91.   These types are required to use UNIT IndexedFiles.  Include IndexStr as
  92.   the first field in the record to be indexed or strange things will happen!
  93.  
  94.   Do not refer to a file created with IndexedFiles with any of the standard
  95.   file variables except in a read only mode.
  96.  
  97. The following is a list of PROCEDUREs and FUNCTIONs exported by IndexedFiles:
  98.  
  99.  
  100. ****   IMPORTANT NOTE  *********
  101.  
  102. Below are notes to be careful with the SizeOf function.  These are generic
  103. routines that care little if you use the correct size in calls as they will
  104. gladly read less bytes than actual record size, read more bytes ( overwriting
  105. data at best, code at worse, etc.  This is bad!  and good.  Used correctly,
  106. these routines can write several record types to one file!  And index them!
  107. The only requirement is a ten byte string ( ok 11 counting length! ), you can
  108. use the first X bytes to identify the record type, etc.
  109.  
  110. All is up to how clever you are at coding....Enjoy.
  111.  
  112. ********************************
  113.  
  114. ------------------------------------------------------------------------------
  115.  
  116.  PROCEDURE   ReadIndexed ( VAR f                 : IFile ;
  117.                            VAR buffer                   ;
  118.                                size              : WORD ) ;
  119.  
  120.     This procedure will read size bytes into buffer from the file represented
  121.     in f.  You must place the index you want in buffer before making the call.
  122.  
  123.     Example,
  124.  
  125.             anyRec.index := '0000056790' ;
  126.             ReadIndexed ( indexFile , anyRec , SizeOf ( AnyRecType ) ) ;
  127.  
  128.     I STRONGLY recommend using the RECORD TYPE in the SizeOf function.  This
  129.     will in sure the correct number of bytes are read.  ReadIndex has no way
  130.     of insuring anyRec is the correct type for the file.  BE CAREFUL.
  131.  
  132. -----------------------------------------------------------------------------
  133.  
  134.  PROCEDURE   WriteIndexed ( VAR f                : IFile ;
  135.                             VAR buffer                  ;
  136.                                 size             : WORD ) ;
  137.  
  138.     This procedure will write size bytes from buffer to the file represented
  139.     in f.  You must place the index you want in buffer before making the call.
  140.     If index is found, the file pointed to by index will be replaced.  If the
  141.     index is new, the record is appended to the base file and a new index is
  142.     written to the index file.
  143.  
  144.     Example,
  145.  
  146.             anyRec.index := '1000000000' ;
  147.  
  148.             WITH anyRec DO
  149.              BEGIN
  150.  
  151.                {  Make assignments  }
  152.  
  153.              END ;  {  WITH  }
  154.  
  155.             WriteIndexed ( indexFile , anyRec , SizeOf ( AnyRecType ) ) ;
  156.  
  157.     I STRONGLY recommend using the RECORD TYPE in the SizeOf function.  This
  158.     will in sure the correct number of bytes are written.  WriteIndex has no
  159.     way of insuring anyRec is the correct type for the file.  BE CAREFUL.
  160.  
  161. ------------------------------------------------------------------------------
  162.  
  163.  PROCEDURE   ResetIndexed ( VAR f                : IFile ) ;
  164.  
  165.     This procedure will Reset the data file and the index file.
  166.  
  167. ------------------------------------------------------------------------------
  168.  
  169.  PROCEDURE   ReWriteIndexed ( VAR f              : IFile ) ;
  170.  
  171.     This procedure will ReWrite all files used for indexing.  This is
  172.     required to create the indexed file.
  173.  
  174. ------------------------------------------------------------------------------
  175.  
  176.  PROCEDURE   CloseIndexed ( VAR f                : IFile ) ;
  177.  
  178.     This procedure will close both files involved with the indexing.
  179.  
  180. ------------------------------------------------------------------------------
  181.  
  182.  FUNCTION    FilePosIndexed ( VAR f              : IFile ;
  183.                                   size           : WORD )
  184.                                                  : LONGINT ;
  185.  
  186.    This function will report the current position in indexed file f of given
  187.    size.  I'm not really sure why one would want to know, but the feature
  188.    is here.
  189.  
  190. ------------------------------------------------------------------------------
  191.  
  192.  PROCEDURE   AssignIndexed ( VAR f               : IFile ;
  193.                                  indexFile       : STRING ) ;
  194.  
  195.    This procedure will assign the files to the base file given in indexFile.
  196.    paths are accepted, but extensions are not.  Three files are built from the
  197.    supplied name.
  198.  
  199. ------------------------------------------------------------------------------
  200.  
  201.  FUNCTION    FileSizeIndexed ( VAR f             : IFile ;
  202.                                    size          : WORD )
  203.                                                  : LONGINT ;
  204.  
  205.    This function will return the number of record of size bytes held in the
  206.    main file.  This number does not take into account either index file, but
  207.    these are relatively small  ( 15 bytes per entry ).
  208.  
  209. ------------------------------------------------------------------------------
  210.  
  211.  FUNCTION    IndexFileSize ( VAR f               : FILE )
  212.                                                  : LONGINT ;
  213.  
  214.   This function is included for completeness.  It merely calls FileSize on
  215.   the main file.  The answer returned is in bytes and represents the total
  216.   file size of the main file ( IE, excluding index files ).
  217.  
  218. ------------------------------------------------------------------------------
  219. --                                                                          --
  220. --  The following PROCEDURES and FUNCTIONS added with VERSION 1.5           --
  221. --                                                                          --
  222. ------------------------------------------------------------------------------
  223.  
  224.  PROCEDURE   DeleteIndexed ( VAR f               : IFile ;
  225.                              VAR buffer          ;
  226.                                  size            : WORD ) ;
  227.  
  228.   OK, I forgot this PROCEDURE in version 1.0 :-).  Call this procedure to
  229.   remove the index entry and the record from the base file.  This is an
  230.   involved process!  The index file must be updated since it relies on the
  231.   binary location of files in the base file.  I decided the extra overhead
  232.   in deleting the record now was justified since it frees us of having to
  233.   mark deleted record, keep track of them, and finally remove them ( or
  234.   waste time when inserting new records looking for them.  Most operations will
  235.   be inserting and update - ReadIndexed and WriteIndexed do this as quickly
  236.   as possible.
  237.  
  238. ------------------------------------------------------------------------------
  239.  
  240.  FUNCTION    IndexFileSize ( VAR f               : FILE )
  241.                                                  : LONGINT ;
  242.  
  243.   This FUNCTION will return the number of index records in the index file.
  244.   Besides being a handy way to determine the number of records in you file,
  245.   It is the only way to really sequentially process the file.  See IndexRead
  246.   below.
  247.  
  248. ------------------------------------------------------------------------------
  249.  
  250.  PROCEDURE   IndexSeek ( VAR f                   : FILE ;
  251.                              position            : LONGINT ) ;
  252.  
  253.   This procedure will position the index file pointer in the index file.
  254.  
  255. ------------------------------------------------------------------------------
  256.  
  257.  PROCEDURE   IndexRead ( VAR f                   : FILE ;
  258.                          VAR tempIndex           : IndexType ) ;
  259.  
  260.  
  261.  This PROCEDURE will allow you to Read an index record from the index file.
  262.  Combined with the IndexFileSize FUNCTION, you can easily process your file
  263.  sequentially.
  264.  
  265.  EX,
  266.  
  267.  ....
  268.  
  269.  numberRecords := IndexFileSize ( f.indexFile ) ;
  270.  idx := 0 ;
  271.  WHILE ( ( NOT ( EOF ( f.indexFile ) ) ) AND ( idx <= numberRecords ) )
  272.   DO
  273.    BEGIN
  274.      IndexSeek ( f.indexFile , idx ) ;
  275.      IndexRead ( f.indexFile , tempIndex ) ;
  276.      yourRecord.index := tempIndex.index ;
  277.      ReadIndexed ( f , yourRecord , SizeOf ( yourRecord ) ) ;
  278.      ....  PROCESS DATA  .......
  279.    END ;  {  WHILE  }
  280.  
  281.  
  282. ------------------------------------------------------------------------------
  283.  
  284. ------------------------------------------------------------------------------
  285. --                                                                          --
  286. --  The following FUNCTION added with VERSION 1.7                           --
  287. --                                                                          --
  288. ------------------------------------------------------------------------------
  289.  
  290.  FUNCTION    IndexedError (     errorNum         : WORD ;
  291.                                                  : STRING ;
  292.  
  293.   This FUNCTION will return text explaining the error in simple terms.
  294.  
  295. ------------------------------------------------------------------------------
  296.  
  297. ******************************************************************************
  298.  
  299. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  300. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  301.  
  302. ******************************************************************************
  303.  
  304.                     SECTION TWO : Files
  305.  
  306. ******************************************************************************
  307. **                                                                          **
  308. **  No changes from version 1.7 to version 1.8                              **
  309. **                                                                          **
  310. ******************************************************************************
  311.  
  312.    There are only two exported procedures.  These will allow you to delete or insert any number of bytes into a file.  It takes available memory into account ( up tp 64K limit ) in the BlockRead/BlockWrites and is very quick.  As with all the units included here, be careful!  With versatility usually comes danger if one is not careful, but there is an equal potential with a little care and common sense!
  313.  
  314. ******************************************************************************
  315.  
  316.  
  317. Below is a list of the possible errors reported by this unit.
  318.  
  319.        FILE_POSITION_OUT_OF_RANGE                = 1 ;
  320.        FILE_READ_ERROR                           = 2 ;
  321.        FILE_WRITE_ERROR                          = 3 ;
  322.  
  323. Below is the general purpose error variable exported by this unit.  When
  324. using the unit in a program that USES IndexedFiles ( or another of my UNITS ),
  325. be sure to use Files.fileError or IndexedFiles.fileError so the compiler will
  326. resolve your reference as you meant, and not by the order you USEd the Units!!
  327.  
  328.        fileError                                 : WORD ;
  329.  
  330. Finally, here are the PROCEDUREs exported by the UNIT.
  331.  
  332.  
  333.  PROCEDURE   InsertRecord ( VAR f                : FILE ;
  334.                             VAR buffer                  ;
  335.                                 position         : LONGINT ;
  336.                                 lRecL            : WORD ) ;
  337.  
  338.    This procedure will insert lRecL bytes from buffer into file f at binary
  339.    position.  What's that mean?  It will place lRecL bytes into
  340.    file f at absolute position ( lRecL * position ).  All records from this
  341.    position to the end of the file will be shifted down lRecL bytes.
  342.  
  343. -----------------------------------------------------------------------------
  344.  
  345.  PROCEDURE   DeleteRecord ( VAR f                : FILE ;
  346.                                 position         : LONGINT ;
  347.                                 lRecL            : WORD ) ;
  348.  
  349.    This procedure will remove lRecL bytes from file f at absolute position
  350.    ( lRecL * position ).  All bytes following this will be shifted over this
  351.    record and the file length will be truncated by lRecL bytes.
  352.  
  353. ******************************************************************************
  354.  
  355. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  356. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  357.  
  358. ******************************************************************************
  359.  
  360.                     SECTION THREE : AsmRoutines
  361.  
  362. ******************************************************************************
  363. **                                                                          **
  364. **  Sorry this Missing UNIT might have caused some problems.   TEJ          **
  365. **                                                                          **
  366. ******************************************************************************
  367.  
  368. This is a new section.  There are several useful routines here.
  369. As was stated earlier in this file, two of the routines are modified from
  370. Borland personnel code.  Please remember that the original ideas there
  371. are not mine.
  372.  
  373. ******************************************************************************
  374.  
  375.  
  376. Here are the FUNCTIONs exported by this UNIT:
  377.  
  378.  
  379.  
  380.  FUNCTION    HexStr ( VAR num                    ;
  381.                           numberOfBytes          : BYTE )
  382.                                                  : STRING ;
  383.  
  384.    This FUNCTION will return a string of HEX digits that equals the number
  385.    passed into num.  This will work for any valid number ( even arrays of
  386.    numbers ).  Remember that a string can hold 255 characters maximum, so this
  387.    FUNCTION is limited to HEXing 128 bytes at a time MAX ( two hex digits per
  388.    byte ).  The assembly PROC used was created by Borland personnel and adapted
  389.    to the TPascal MODEL by me.
  390.  
  391. -----------------------------------------------------------------------------
  392.  
  393.  PROCEDURE   Exchange ( VAR var1                 ;
  394.                         VAR var2                 ;
  395.                             count                : WORD ) ;
  396.  
  397.    This PROCEDURE will exchange any to variables ( max 64K size ) using
  398.    NO temp variable.  How?  It uses string instructions to load a register
  399.    at a time meaning no temp storage needed and a great speed dividend.  This
  400.    assembly PROC was created by Borland personnel and adapted to the TPascal
  401.    MODEL by me.
  402.  
  403. -----------------------------------------------------------------------------
  404.  
  405.  FUNCTION    Compare ( VAR var1                  ;
  406.                        VAR var2                  ;
  407.                            strng                 : BOOLEAN ;
  408.                            count                 : WORD )
  409.                                                  : INTEGER ;
  410.  
  411.    This FUNCTION will compare any two variables.  It returns -1 if var1 < var2,
  412.    0 if var1 = var2, and 1 if var1 > var2.  If strng is set to TRUE, the
  413.    assembly PROC will skip the length BYTE to compare only the actual contents
  414.    of the strings.  Be sure to Use the Length FUNCTION and give the shorter
  415.    length as size to avoid comparing garbage.
  416.  
  417. -----------------------------------------------------------------------------
  418.  
  419. ******************************************************************************
  420.  
  421. EOF ( for now :-) !! )
  422.